package com.googlecode.dgwt.client.dijit;

import com.google.gwt.event.shared.GwtEvent;
import com.google.gwt.event.shared.HasHandlers;

/**
 * Enables a Widget to be composed by a set of another widgets. <br/>
 * Classes that extends {@link Widget} can add views by calling the protected
 * method {@link Widget#addView(View)}. <br/>
 * <br/>
 * Example: <br/>
 * <code>
 * <br/>
 * {@literal @}Override </br>
 * protected void {@link Widget#buildRendering buildRendering}() {<br/>
 * <br/>
 * &nbsp;&nbsp; View myView = new MyView(); <br/>
 * &nbsp;&nbsp; this.loadFromTemplate(myTemplate);<br/>
 * <br/>
 * &nbsp;&nbsp; // add the view element to one of this widget elements <br/>
 * &nbsp;&nbsp; this.getContainerElement().appendChild(myView.getWidget());<br/>
 * <br/>
 * &nbsp;&nbsp; // now the view is part of my widget, so I can add it <br/>
 * &nbsp;&nbsp; this.addView(myView);<br/>
 * }<br/>
 * </code>
 * <br/>
 * Note: you must ensure that the {@link Widget#getElement() main widget
 * element} of a view is physically attached to the parent widget before calling
 * {@link Widget#addView(View)}.
 * 
 * @author wellsantos@wellsantos.com
 * @since 0.01
 */
public interface View extends HasHandlers {

    /**
     * Returns an name for this view. Don't need to be an unique name for the
     * whole application, but the same name should be returned always.
     * 
     * @return the view name
     */
    public String getName();

    /**
     * Returns the widget that represents the view component. <br/>
     * The same widget should be returned always and it can not be
     * <code>null</code>.
     * 
     * @return a widget for this view 
     */
    public Widget getWidget();
    
    /**
     * {@inheritDoc} <br/>
     * Calls to this method should be redirected to the this view {@link #getWidget() widget}.
     */
    public void fireEvent(GwtEvent<?> event);

    /**
     * If two views provides the same {@link #getWidget() widget},
     * <code>true</code> should be returned. <br/>
     * <br/> {@inheritDoc}
     */
    public boolean equals(Object o);
    
    /**
     * {@inheritDoc}
     */
    public int hashCode();
    
}
